/**
 * Hackystat Version 8 Framework
 * Twitter Widget RPC Interface
 */
package org.hackystat.ui.hackerrific.client.common;


import com.google.gwt.user.client.rpc.AsyncCallback;

/**
 * Remote procedure call interface for communicating with the Twitter server. 
 * 
 * @author David J. Nickles
 */
public interface RPCRemoteServiceAsync {
  
  /**
   * Returns an HTTP 200 OK response code and a format-specific response if authentication
   * was successful.  Use this method to test if supplied user credentials are valid with 
   * minimal overhead.
   * @param user user to authentication.
   * @param password user password for authentication.
   * @param callback address of return function.
   */
  public void authenticate(String user, String password, AsyncCallback callback);
  
  /**
   * Favorites the status specified in the ID parameter as the authenticating user.
   * Returns the favorite status when successful.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @param id Required.  The ID of the status to favorite.
   * @param callback address of return function.
   */
  public void createFavorite(String user, String password, String id, AsyncCallback callback);
  
  /**
   * Unfavorites the status specified in the ID parameter as the authenticating user.
   * Returns the favorite status when successful.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @param id Required.  The ID of the status to favorite.
   * @param callback address of return function.
   */
  public void destroyFavorite(String user, String password, String id, AsyncCallback callback);
  
  /**
   * Ends the session of the authenticating user, returning a null cookie.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @param callback address of return function.
   */
  public void endSession(String user, String password, AsyncCallback callback);
    
  /**
   * Returns the 20 most recent statuses from the Twitter server for the specified feed type.
   * @param user user to authentication.
   * @param password user password for authentication.
   * @param type the timeline type: public, friends, user.
   * @param lastId get entries since the last entry id.
   * @param callback address of return function.
   */
  public void timeline(String user, String password, String type, String lastId, 
    AsyncCallback callback);

  /**
   * Send a tweet to the Twitter server.
   * @param user user to authentication
   * @param password user password for authentication
   * @param message the tweet text
   * @param callback address of return function
   */
  public void update(String user, String password, String message, AsyncCallback callback);
  
  /**
   * Returns the version number from the Manifest file.
   * @param callback address of return function.
   */
  public void version(AsyncCallback callback); 
}
